The 640 MEG Shareware Studio 2

home *** CD-ROM | disk | FTP | other *** search

/ The 640 MEG Shareware Studio 2 / The 640 Meg Shareware Studio CD-ROM Volume II (Data Express)(1993).ISO / dbase / do1beta.zip / DO.DOC < prev next >

Wrap

Text File | 1991-08-23 | 165KB | 4,621 lines

dObject Version 1.0 User Guide Object-Oriented Programming Language for DBASE(tm) Copyright (c) 1991 Intelligent Systems Research All Rights Reserved dObject Version 1.0 (c) 1991 Intelligent Systems Research 1.0 Introduction 1.1 Introduction Welcome to Object-Oriented programming for DBASE(tm) ! dObject is an object-oriented programming language with built-in base classes for handling DBASE data, memo, and index files. Using dObject, you can build complex applications that use your existing DBASE files and a class library of over 15 classes and 300 methods. You can define your own classes and methods that inherit the features of the base classes. You can create new DBASE data, memo, and index files, and you can write graphics and full-color windowed hypertext applications that display your DBASE data. dObject includes the following features: * a fast, efficient interpreted language for writing object-oriented DBASE applications * a built-in full screen text editor callable from your applications with hypertext on-line help * over 300 built-in methods for integer and real arithmetic, characters, strings, and dates * a text-mode windowing system * a graphics system based on the Borland BGI * a pop-up menu facility * DBASE-like SAY and GET output to windows, and code for a full screen DBASE field editor * output logging to printers and DOS text files * LAN-compatible row and file locking of DBASE files * a powerful GREP-like pattern matching function for strings and DBASE character fields * a hypertext facility linked to DBASE * multi-dimensional arrays * an advanced Collection class for managing complex data structures * a C-style preprocesssor for constant definitions and program text inclusions - 2 - Chapter 1: Introduction dObject provides the following advantages over the DBASE programming language: * facilities for defining classes and methods that are far superior to the UDF facility in DBASE, including support for inheritance and polymorphism * advanced date handling including international formats, julian dates, and date arithmetic * facilities for providing sophisticated user interfaces for DBASE(tm) applications, including use of multiple, overlapping full-color windows and pop-up menus * facilities for building hypertext applications that use DBASE data and index files * graphics 1.2 Manual Overview This manual is both a user guide and a reference guide to dObject. The chapters include: * Chapter 1 - Introduction * Chapter 2 - Getting Started * Chapter 3 - dObject Statements * Chapter 4 - dObject Classes * Chapter 5 - Numeric Classes * Chapter 6 - Logical Operations * Chapter 7 - Characters and Strings * Chapter 8 - Dates * Chapter 9 - Windows and Menus * Chapter 10 - Arrays and Collections * Chapter 11 - Files and Devices * Chapter 12 - DBASE File Programming * Chapter 13 - BGI Graphics - 3 - dObject Version 1.0 (c) 1991 Intelligent Systems Research 1.3 How to Contact ISR If you need technical support or would like to contact Intelligent Systems Research with comments, suggestions, or questions about dObject, please write to us at: Intelligent Systems Research P.O. Box 3690 Chicago IL 60654 USA (312)-878-6054 CompuServ: Send E-mail to userid 70304,2520 Please include your dObject version number, your computer make and model number, and your operating system make and model number if you have technical questions or need detailed technical support. 2.0 Getting Started 2.1 Hardware Requirements dObject requires the following minimal hardware configuration: * an 80286, 80386 or 80406 CPU * 640KB main memory * a hard disk drive * MS-DOS 3.0 or above 2.2 Installing dObject The shareware version of dObject does not need to be installed beyond the "unzip" of the distribution .ZIP file. The files DO.EXE, HELP.DBF, HELP.DBT, HELP.NDX, ERROR.DBF, ERROR.NDX, and DO.CFG should reside in the hard disk directory "DOBJECT". The registered version of dObject comes with an INSTALL program on the distribution diskette. The INSTALL program will prompt you for the name of a directory to create on your hard disk, and then copy the dObject distribution files to that directory. If you wish, you can duplicate this yourself by issuing the DOS commands below: C:\>md dobject - 4 - Chapter 2: Getting Started C:\>cd dobject C:\DOBJECT>copy a:do.exe C:\DOBJECT>copy a:do.cfg C:\DOBJECT>copy a:*.dbf C:\DOBJECT>copy a:*.dbt C:\DOBJECT>copy a:*.ndx C:\DOBJECT>copy a:*.do C:\DOBJECT>copy a:*.bgi C:\DOBJECT>copy a:*.chr You should also specify the DOBJECT directory as one of the PATH options in your DOS AUTOEXEC.BAT file. dObject will always look in the directory that the DO.EXE file is in for the HELP and ERROR databases (including memo and index files). Make sure that when you install dObject, all these files are in the same directory as the executable file DO.EXE, otherwise the on-line help and error reporting systems will not work properly. Because dObject provides direct access to existing DBASE III format files, and becuase dObject uses several DBASE III files in its runtime environment, you should set the DOS FILES and BUFFERS option in your config.sys file to at least the following values: FILES=20 BUFFERS=20 To run the BGI demonstration program (BGIDEMO.DO) you must also first define a DOS environment variable named BGIPATH. This variable must contain the name of the directory where the supplied BGI drivers and font files are stored. If you install dObject in the directory C:\DOBJECT, you should add this line to your autoexec.bat file: SET BGIPATH=C:\DOBJECT 2.3 Running dObject To run dObject, at the DOS prompt type "do": C:\>do dObject Version 1.0 (Shareware) Copyright (c) 1991 Intelligent Systems Research Please register this version for support and updates Press any key to continue... - 5 - dObject Version 1.0 (c) 1991 Intelligent Systems Research Pressing any key at this point will cause dObject to issue the "dObject> " prompt and accept commands. (The registered version of dObject goes directly to the "dObject> " prompt without pausing; this is a small reminder to register the shareware version !). To run a dObject source program directly from the DOS prompt, type "do" followed by the name of the file to run, with a default extension of "DO". For example, to run the dObject program in the file "demo.do" in the current DOS directory, issue the command: C:\> do demo 3.0 dObject Statements 3.1 Statements dObject accepts statements at the "dObject>" prompt using free-form input. Statements can be entered in any number of lines but must be terminated with a semicolon. dObject will prompt for statement continuation with the "more>" prompt until a semicolon is entered. dObject accepts the following legal statements: STATEMENT DESCRIPTION help; enter online hypertext help system and display table of contents cls; clear screen (current window) exit; exit dObject and return to DOS (also recognizes "quit;") edit <filename>; edit file (default extension .DO) ESC - exit without saving changes; F10 - exit and save changes for(statement;exp;statement) execute statements for range of values <statements> while <exp> <statements> while expression is true execute statements if <exp> <statements> else conditional execution of statements <statements> with else clause if <exp> <statements> conditional execution of statements do <filename>; execute statements in file (default extension .DO) dos; suspend dObject and shell to DOS return(<exp>); return expression as method result show <item>; shows internal information about dObject. "show classes" shows defined classes, "show methods" shows defined methods, "show set" shows SET variables, "show variables" shows all defined user variables switch (exp) {<cases>} conditional execution of cases ? <exp>[,<exp>...]; print expression values in current - 6 - Chapter 3: dObject Statements window <exp>; evaluate the expression dObject accepts comments within source programs using the conventions of the "C" programming language. Comments must begin with the characters "/*" and end with the characters "*/". All characters in between, including spaces, tabs, and newlines, are treated as comment characters and are ignored by the interpreter. The following example demonstrates legal dObject comments: /* this is a comment */ method Int::zero(self) /* comments are allowed anywhere */ { return(0); % this is an end-of-line comment } To exit from dObject and return to the DOS prompt, issue the "exit" command: dObject> exit; To review the on-line hypertext help, issue the "help" command: dObject> help; dObject provides a way to execute other dObject program source files through the use of the "do" command with a filename to execute. dObject will supply a default extension of ".do" if you do not supply one. For example, to execute the statements in the file "test.do", issue the statement: dObject> do test; 3.2 Errors If you make an error in a dObject statement, dObject will attempt to locate the error and print out the offending statement with a relevant error message. The error display will be shown in an Error window displayed in the lower left corner of the screen. The complete list of error codes generated by dObject is contained in the supplied file ERROR.DBF. - 7 - dObject Version 1.0 (c) 1991 Intelligent Systems Research To produce the error displauy, dObject calls the built-in Int::onError() method and passes it the Int error code of the error. You can re-define this method in your applications to change the way that error messages are displayed: /* demonstration of the Int::onError() method this method is called whenever dObject detects a parse or runtime error in a program; normally dObject creates a 1-line window at the bottom of the display screen and prints out the error number, an error message, and the statement where the error was detected. you can re-define this method to handle errors for your own applications */ method Int::onError(self) { w = new(Window,1,112,112," Error ",10,10,5,50); db = new(Dbffile,"error"); ndx = new(Ndxfile,db,"error"); seek(db,self); ? "ERROR ",self,": ",msg; readchar(); remove(w); } /* cause an error */ exit(10002); 3.3 Breaks To interrupt a dObject program during execution, press the Control key and the Break key at the same time (Ctrl-Break). This will cause dObject to issue an error message for the break, and then return to the dObject> prompt. 3.4 Preprocessor dObject includes a built-in preprocessor for defining compile-time constants and file includes. dObject accepts constant definitions of the form: #define NAME VALUE - 8 - Chapter 3: dObject Statements where NAME is the name of the constant to define, and VALUE is the value to assign to it. Values can be any single token of text, or any string of text delimited with double quotes. For example, the following are all legal dObject constant definitions: /* define some commonly used integer codes for characters */ #define ESC 27 #define CR 13 #define TRUE "T" /* define an alias name for a dObject function */ #define CURRENT_DATE "date()" Whenever dObject encounters a defined constant anywhere in the text of a program, it will substitute the defined text before parsing and executing the statement. Use of this technique makes your programs more readable and understandable. For example, the following code uses the constants defined above: /* read a character from the keyboard */ c = inkey(); if(c == ESC) ? "the escape key was pressed"; if(c == CR) ? "the return key was pressed"; A file can be included in the source text before it is parsed by using the "include" directive: #include "keydef.do" 3.5 Variables In dObject, variables are used to store any kind of value in memory for use by your program. The names of these variables must begin with a lower case alphabetic character (since upper case names are reserved for class names); and can then contain any number of alphabetic or numeric characters, as well as the underscore. The variable name must not be one of the following dObject reserved keywords: while, for, if, then, else, do, return or method. For example, the following are legal dObject variable names: * a - 9 - dObject Version 1.0 (c) 1991 Intelligent Systems Research * a1 * my_variable The following are NOT legal variable names: * 1a (begins with a numeric character) * My_variable (begins with an uppercase character) * my-variable (uses the '-' character) * while (uses the reserved dObject keyword while) Variables use memory space within dObject that can be re-used later if your program no longer needs the variable. To reclaim the storage space for a variable, send the "release" message to an Exp object containing the name of the variable: dObject> a = 32; dObject> release(#a); 3.6 Literals Literal values are sequences of numbers, letters, and special characters that are interpreted as actual values by dObject, not variable names. dObject accepts literal values in the following formats (note that hex integer constants are defined using a leading dollar sign): CLASS FORMAT EXAMPLE Nil: nil nil Date: mm/dd/yyyy 5/10/1990 Char: 'c' 'a' String: "ccc" "this is a string" Int (decimal): n 123 Int (hex): $n $1ff Long: nL 123L Real: n.d 12.34 Logical: T or F T Collection: [v1,v2,v3...] [1,2,$1ff,T,3.3,"four",'5',(1,"one"),5/10/90] Exp: #exp #date() 3.7 Expressions Expressions in dObject are combinations of literal values, variable names, and "messages". Messages are sent to objects in dObject either as operators or as named messages. Operators are special characters (usually one or two characters) that have a special meaning when - 10 - Chapter 3: dObject Statements applied to values, and are generally used in messages of the form "object operator object". For example, in dObject the expression 1 + 2 means send the "plus" message to Int 1 with an argument of Int 2. Named messages are always of the form name(object,args), where "name" is the name of the message to send, "object" is the object to send the message to, and "args" is zero or more values to use as arguments to the message. For example, the expression "clear(w)" in dObject means send the "clear" message to the object stored in the variable "w" (presumably a Window object) with no argument. The only exception to this convention are messages sent to the Nil object, which effectively have no object or arguments in the calling sequence. The expression "memory()" means send the "memory" message to the Nil object. dObject allows the assignment of values and expressions to variables through the use of the assignment operator, denoted by the equals (=) sign: dObject> v = 1+2*3; dObject recognizes literal expressions beginning with the '#' character and defers evaluation of the expression until runtime. Such expressions are useful when you are actually passing an expression to a method to evaluate later, such as using the built-in "avg" method on a DBASE(tm) file. The argument to the "avg" method is an expression to evaluate for each record in the file. For example, the following statements print the average length of the "lname" field within a DBASE(tm) file: dObject> db = new(Dbffile,"patient"); dObject> ? avg(db,#len(trim(lname))); Passing the literal expression #len(trim(lname))) instructs dObject to defer evaluating the expression until the "avg" method runs; if you forget the '#' sign before the expression, dObject will evaluate the expression and pass the resulting Int value to the "avg" method as an argument, which will result in an error ! 3.8 Program Control Statements dObject provides the "for", "while" and "switch" statements to control the flow of program execution, all of which are similar to their counterparts in the C programming language. The "for" statement executes a block of statements while an iteration expression is true: - 11 - dObject Version 1.0 (c) 1991 Intelligent Systems Research /* demonstrate the for statement */ for(i=0;i<10;i=i+1) ? i; In this case, dObject will execute the first statement in the for expression, i=0, and then execute the statements in the block after the for expression. After each pass through the block, the statement i=i+1 will be executed, and the expression i<10 evaluated. If the expression is true dObject will continue to execute the statement block. Execution stops whenever the expression is found to be false. After the for statement is completed any variables used in the statements will still exist; in the above example i will have the value of 11 after the for statement executes. The "while" statement executes a block of statements while an expression evaluates to logical "true": /* demonstrate the while statement */ i = 1; while(i < 10) { ? " i = ",i; i = i+1; } The "switch" statement is similar to the one found in the C programming language. An expression is evaluated and then matched against the values found in a series of "case" statements. The first case matching the expression value is executed: /* demonstrate the switch statement */ i = 3; switch(i) { case 1: ? "i is one "; case 2: ? "i is two "; case 3: ? "i is three "; case 4: ? "i is four "; } In the above example only the statement ? "i is three " would execute within the switch. - 12 - Chapter 3: dObject Statements 3.9 Editing Text Files dObject provides a built-in full screen text editor for creating and modifying text files, including dObject source files. To invoke the editor, issue the "edit" command followed by the name of the file in the current directory to edit. dObject will supply a default extension of ".DO" for the file to make it easy to edit dObject source files. For example, to edit the file "test.do", issue the command: dObject> edit test; dObject will invoke the text editor in the current window, which by default is the full screen. Editing can occur in other windows by first creating the window and the issuing the "edit" command. The built-in editor is similar to the WordStar(tm) text editor and responds to the following keystroke commands: FUNCTION KEY View dObject help for word at cursor Ctrl-F1 Move cursor right one character right arrow Move cursor left one character left arrow Move cursor up one line up arrow Move cursor down one line down arrow Scroll up one line Ctrl-W Scroll down one line Ctrl-Z Move cursor right one word Ctrl-Right arrow Move cursor left one word Ctrl-A Move cursor to right end of line End Move cursor to left end of line Home Move cursor to top of window Ctrl-Home Move cursor to bottom of window Ctrl-End Move cursor up one screen PgUp Move cursor down one screen PgDn Move cursor to top of file Ctrl-PgUp Move cursor to bottom of file Ctrl-PgDn Delete character at cursor Del, Ctrl-G Delete character left of cursor Backspace Delete word at cursor Ctrl-T Delete line at cursor Ctrl-Y Delete left from cursor to start of line Ctrl-Q T Delete right from cursor to start of line Ctrl-Q Y Mark beginning of block Ctrl-K B Mark end of block Ctrl-K K Copy (insert) marked block at cursor Ctrl-K C Move (insert) marked block at cursor Ctrl-K V Delete marked block Ctrl-K Y Write marked block to diskfile Ctrl-K W Write marked block to printer Ctrl-K P - 13 - dObject Version 1.0 (c) 1991 Intelligent Systems Research Block select on/off Ctrl-K M Copy block to pastebuffer Ctrl-K I Move block to pastebuffer Ctrl-K Y Paste Ctrl-U Search Ctrl-F3 or Ctrl-Q F Search again Shift-F3 or Ctrl-O Replace F4 Replace again Shift-F4 or Ctrl-L The key assignments for the editor are contained in the file "do.cfg" that is loaded at runtime by dObject. You can change these default combinations by calling the Nil::setupKeyboard() method from the dObject prompt, changing the key assignments using the menu choices provided, and then saving the current key configuration using the String::saveConfig method. The following example illustrates this procedure: dObject> setupKeyboard(); dObject> saveConfig("new.cfg"); dObject> exit; C:\DOBJECT:> rename do.cfg old.cfg C:\DOBJECT:> rename new.cfg do.cfg From within the Nil::setupKeyboard() method, a series of menu choices will be presented that allow you to choose the particular functions within the editor to be re-assigned to a key or keystroke combination. To redefine a command's keystroke(s), highlight the menu item for the command using the arrow keys and press Enter. In the input box that appears, you can define one or two sets of keystrokes for the command. Press Enter to skip over the first set of keystrokes, or press the new key combination for the first setup and then press Enter. When the cursor is in the second column, press Enter to skip the second setup, or press a new key combination followed by Enter. To abort this process at any time press the Esc key. Your application can load a special .CFG file at runtime using the String::loadConfig method and passing it the name of the file to load. The file should be one of the supplied .CFG files that comes with dObject, or a .CFG file you have created using the procedure described above. Comprehensive on-line help for editor commands is available from within the editor by pressing the F1 key. Help for dObject statements and built-in classes and methods is available from within the editor by placing the cursor on a dObject keyword, class name, or method name and pressing the Ctrl-F1 key. - 14 - Chapter 3: dObject Statements 3.10 Input and Output Statements The "?" statement prints the value of an expression onto the current window, followed by a carriage return and line feed: dObject> ? 1+1; 2 dObject> The String::accept() method provides a simple way to write a prompt and read Strings from the keyboard: dObject> line = accept("enter value> "); For a detailed description of the input, output, and file handling capabilities of dObject, refer to the chapters titled "Files and Devices" and "Windows and Menus" later in this manual. 3.11 Output Logs dObject will also log the output from the "?" command to a file and/or an attached printer using the built-in log feature. Pressing the ALT-P key combination will display a popup menu showing the current on/off status of the logs to the printer and to the file PROLOG.LOG. To toggle the status from off to on and vice versa, use the arrow keys to position the menu bar, and press the RETURN key to toggle the value. Press the ESC key to exit the menu and return to the dObject prompt. 3.12 Environment Variables dObject maintains a small set of environment variables that can be set using the String::set() method and interrogated by the "show" command. These environment variables are: VARIABLE DEFAULT DESCRIPTION echo F when true, causes dObject to echo the statement just about to be executed to the current window hyperhelp T when true, allows use of Ctrl-F1 key from within editor to access dObject help stored in HELP.DBF file; when false, disables Ctrl-F1 newline nl dObject will print this value at the end of each "?" statement prompt "dObject>" the String to be used as the command prompt - 15 - dObject Version 1.0 (c) 1991 Intelligent Systems Research softseek F when true, all String comparisons return true (T) if a "partial match" occurs; that is if the first string being compared is a substring of second string. when off, dObject returns true only if the strings being compared are identical, including trailing blanks space "" dObject will print this value between expressions in the "?" statement; normally set to a null String status T when true, status lines appear for text editor, window resize, etc. when false, turns off display of all status lines step F when true, causes dObject to pause between executing statements and print the message: Press SPACE to continue, ESC to abort... pressing the space key executes the next statement pressing the ESC key returns to the dObject> prompt To set an enviroment variable to a value, use the String::set method, with the "self" argument set to the name of the SET variable: dObject> set("echo",T); For example, to change the dObject prompt, set the prompt variable: dObject> set("prompt","--> "); --> To show the value of all the environment variables, use the "show set" command: dObject> show set; echo=logical(false) step=logical(false) softseek=logical(false) status=logical(true) hyperhelp=logical(true) prompt=string("dObject> ") space=char(' ') The value of a particular set variable is available by calling the String::set() method with self set to the name of the set variable to retrieve and with no other arguments: dObject> ? set("echo"); F - 16 - Chapter 3: dObject Statements To show all the currently defined dObject variables, use the "show variables" command: dObject> a = 1; dObject> b = 2; dObject> show variables; a=1 b=2 To show all the classes you have defined in a dObject session beyond the built-in classes, use the "show classes" command (refer to the next chapter for a description of how to create these classes): dObject> show classes; To show all the methods currently defined, use the "show methods" command. 3.13 The RETURN Statement The return statement is used to return a value from a dObject method back to a calling program. The format of this statement is return(exp), where exp is any dObject expression as described above. The use of this statement is appropriate only when defining you own dObject classes and methods, a topic that is described in detail in the next chapter. 4.0 dObject Classes 4.1 Objects dObject provides a powerful facility for you to write complex applications using the "Object" paradigm. With this way of thinking, you define an object as something within the problem you are trying to solve that you want the computer to represent and store information about. For example, in a small business accouting system, the objects might include Companies, Departments, Employees, Products, and Accounts, to name but a few. Each of these objects has a certain correct behavior in the computer, such as a behavior to add a new Employee to a Company, or a behavior for calculating the profit from the sale of a Product to a Customer. In dObject, the object types within the application are called "Classes", and the rules that tell the computer how a class is to behave are called "Methods". Each class has a set of methods that it - 17 - dObject Version 1.0 (c) 1991 Intelligent Systems Research knows about that allow it to perform calculations on the class. dObject provides a large library of built in classes, each with its own set of methods, that allow you to create complex applications right away. However, to fully exploit the power of object-oriented programming, you will eventually want to create your own classes and methods that apply directly to the problems you want to solve. You create these new classes and methods by building them on top of the existing classes and methods. 4.2 Class Definitions To create a new object class, use the "inherit" message on an already existing dObject class: inherit(Parentclass,Newclass,variables); where "Newclass" is the name of the new class to define, "Parentclass" is the class to inherit from, and "variables" is an array of strings that name instance variables within the class. In dObject, the names of classes must always begin with an uppercase letter, followed by upper or lower-case characters or numerals. For example, the statement: inherit(Date,Mydate,["julian"]); You should use the "Nil" class as a parent class that does not inherit data or methods from any parent. To create a variable of a given class type, use the "new" message: v = new(Class,arguments) where "v" is the name of the variable to create, and "Class" is the object class of the variable. For example, to create a new instance of the "Mydate" class and store it into a variable named "d", use the statement: d = new(Mydate); dObject provides a number of base classes as building blocks, including: * Nil - an empty class * Int - 2-byte signed integers - 18 - Chapter 4: dObject Classes * Long - 4 byte signed integers * Real - floating point numbers * Char - single characters * String - strings of characters (up to 64K in length) * Logical - true (T) or false (F) * Date - dates * Array - an array of object at locations indicated by an index * Collection - an ordered collection of objects * File - DOS ASCII text files and devices (such as the printer) * Exp - literal dObject expressions that can be passed as arguments * Dbffile - DBASE files * Ndxfile - DBASE index files * Address - addresses of other objects The class of any dObject variable can always be found by sending the object the built-in "class" message: dObject> ? class(5/10/91); Date dObject> ? class("this is a test"); String dObject> ? class(T); Logical 4.3 Method Definitions To create a named method for a class, use the format: method Class::name(self,arguments) { statements... } - 19 - dObject Version 1.0 (c) 1991 Intelligent Systems Research Values are returned to the calling program through the use of the "return" statement. This should be the last statement executed from within a method. Methods that do not use a "return" statement have a return value of Nil. The special variable "self" always refers to the specific instance of the object that the method is being performed on. You can treat "self" as any other argument in the calling sequence. For example: method Mydate::asString(self) { return(asString(slot(self,"julian")); } defines a method for the "Mydate" class to convert itself to a String. To define an operator for a class, use the character representing the operator as the method name. For example, to define the '+' operator for the Mydate class: method Mydate::+(self,d) { return(asDate(julian(self) + julian(d))); } Variables within a class can be set by using the "replace" method, and referenced by the "slot" method. However, these two methods are only available from within methods defined for the class! This implements an important feature of object-oriented programming: data hiding. Using data hiding, it is good programming form to provide a method that returns the value of a variable within a class, instead of allowing a calling program to access that variable directly. That way, if the implementation of the object changes at some later date, and the variables within the class change, only the methods for the class need to understand the change ! The "outside world" still accesses information about the class through the methods. 4.4 Private Methods By default, methods defined using the syntax described above are "public" in scope - they are available to any other method or main program that wants to use them. In some cases, however, you may wish to define methods that are hidden from other methods in the same way that variables are hidden. dObject lets you do this by substituting the keyword "private" for "method" in the method definition. The following example shows how to define a private method for a class: - 20 - Chapter 4: dObject Classes private Mydate::yearPlusOne(self) { return(year(self)+1); } In the example above, the "yearPlusOne" method is only available to other methods of the Mydate class. Attempts to call it from a method of another class or from a main program will generate an error message. The following example illustrates the use of a private method: /* demo of a private method for a class private methods are only callable from within a method for a class */ inherit(Nil,Temp,[]); private Temp::testPrivate(self) { ? "within testPrivate"; } method Temp::test(self) { ? "enter Temp::test"; testPrivate(self); ? "exit Temp::test"; } v = new(Temp); test(v); % this will work, Temp::testPrivate will be called by Temp::test ? "the next statement will cause an error !..."; testPrivate(v); % this will cause an error ! 4.5 Friend Classes In some cases, you may wish to share the variables and/or the private methods defined for a class with another class. In this case, dObject provides the Exp::friend() method to allow such access. The following example shows how to define one class as a friend of another: /* demo of a private method for a class private methods are only callable from within a method for a class */ - 21 - dObject Version 1.0 (c) 1991 Intelligent Systems Research inherit(Nil,Temp,[]); inherit(Nil,Temp2,[]); /* defining class Temp2 as a friend of class Temp means that methods of Temp2 can access variable and private methods of Temp */ friend(Temp,Temp2); /* define a private method for Temp */ private Temp::testPrivate(self) { ? "within Temp::testPrivate()"; } /* define a public method for Temp2 that creates a variable of type Temp and calls a private method for it */ method Temp2::test(self) { ? "enter Temp2::test"; v = new(Temp); testPrivate(v); % this won't work unless Temp2 is a friend of Temp ! ? "exit Temp2::test"; } v = new(Temp2); test(v); 4.6 Inheritance dObject stores variables for classes you define by allocating storage for a variable of its parent class type, and storage for all the variables defined in the "inherit" statement for its class. For example, consider a class called "Time" that inherits its behavior from the Date class. The "Time" class also contains internal variables for hours, minutes, and seconds, as defined in the following statement: dObject> inherit(Date,Time,["hours","minutes","seconds"]); A new variable of type "Time" can be constructed as follows: dObject> t = new(Time,7/20/1990,1,2,3); - 22 - Chapter 4: dObject Classes Internally, the variable "t" would be stored as an object of class "Time", with 4 internal variables. The first variable is of type Date (the parent class), with the value of 7/20/1990. The remaining variables are the values for "hours", "minutes", and "seconds" as defined in the inherit statement above, with values of 1, 2, and 3 respectively. dObject classes "inherit" all the variables and methods from their parent class. If you send a message to a variable of a class you create and a method for the message has not been defined, dObject will begin searching backwards through the parent class(es) to try to find a method definition it can use. If a method is found, the variable storing the parent class value is passed to the method, without any of the variables for the original class. This process continues until no more parent classes are found. For example, if you send the "asString" message to a Time variable as defined below, and you have not defined a version of "asString" for the Time class, then dObject will take the parent Date value and send it the "asString" message: dObject> inherit(Date,Time,["hours","minutes","seconds"]); dObject> t = new(Time,7/20/1991,1,2,3); dObject> ? asString(t); 7/20/1991 4.7 Parameter Passing dObject normally passes arguments to methods by creating an internal stack and pushing the value for all the arguments to the method onto it. This is exactly the way the C language calls functions. However, in dObject, this implies that you cannot internally change the value of a variable within a class, but must instead return a copy of the variable containing the change. This leads to an easy error to make: /* define a class for Money */ inherit(Int,Money,["cents"]); method Money::setCents(self,c) { return(replace(slot(self,"cents"),i)); } /* - 23 - dObject Version 1.0 (c) 1991 Intelligent Systems Research create a variable of type Money */ m = new(Money); setCents(m,100); % this is wrong ! While it may appear simple to set a Money variable to a value from a calling program, be careful ! You must remember to store the returned copy of the variable back into itself: /* assign "m" a value the wrong way */ setCents(m,100); % this returns a copy of m with "cents"=100 that is lost /* assign "m" a value the right way */ m = setCents(m,100); % this stores the copy back in m ! dObject allows a program to circumvent the need to always pass copies of variables around through the use of the Address class. Using the "address-of" operator (the "&" symbol, as in C), you can instead pass the address of a variable to a method: setCents(&m,100); However, to do this correctly, the method must be expecting an address of a variable and not a copy of the variable itself. This is done by using an asterik before the argument in the method definition wherever an address is to be used. The following example shows how to define and use a method that replaces the value of an internal class variable directly in memory: /* define a new version of the setCents method that replaces a memory location and does not return a copy */ method Money::setCents(*self,c) { replace(slot(*self,"cents"),c); } /* now this is OK ! */ m = new(Money); setCents(&m,100); % m will be updated in-place - 24 - Chapter 4: dObject Classes To access the contents of an address, use the "contents" operator (the asterik character), again just like in the C language: dObject> ?class(&1); Address dObject> ? *&1; 1 4.8 Space Management To reclaim the space used by a variable, send an expression containing the name of the variable the "release" message: dObject> a = 1; dObject> release(#a); To reclaim the space used by a method definition once it is no longer needed by your program, use the "release" method of the Exp class. Send the message to the Class name for the method you wish to delete, and pass the message a String argument containing the method name: dObject> release(Myint,"value"); To reclaim all the space used by a class, including its definition, its methods, and any variables, use the releaseClass method: dObject> releaseClass(Mydate); 4.9 Input and Output To print the value of an object (while executing the "?" command, for example), dObject first sends the object the "asString" method to try to convert it to a String. If this succeeds, the resulting String is printed and the next object to print is processed. Each of the built-in classes provided in dObject has an asString method defined for it. If there is no such method for the class, dObject attempts to print a representation of the internal form of the object. For user defined classes, this printout will be of the form: object(Class,[slot(Name,Value)...]) 4.10 Sample Application As a final example of how to create classes and methods, the following program completes the implementation of the abstract class "Money" used in the examples above: - 25 - dObject Version 1.0 (c) 1991 Intelligent Systems Research /* this is an example of a class to handle money as an abstract type first, define a Money class with a variable to hold an integer number of cents; this will be converted into dollars and cents whenever the Money variable is converted to a String */ inherit(Int,Money,[]); /* set the number of cents in self NOTE: self must be passed by address for this to work ! */ method Money::setCents(*self,c) { replace(parent(*self),c); } /* return the number of dollars in self */ method Money::dollars(self) { return(self/100); } /* return the number of cents in self */ method Money::cents(self) { return(self - (dollars(self)*100)); } /* the "asString" method allows a Money variable to be converted to a String and/or printed */ method Money::asString(self) { return("$ "+asString(dollars(self))+"."+format(cents(self),"%02d")); } method Int::asMoney(self) { return(new(Money,self)); } /* test case */ m = new(Money,100); setCents(&m,104); - 26 - Chapter 4: dObject Classes ? m; ? asMoney(m+1); ? asMoney(m*10); 5.0 Numeric Classes 5.1 Numeric Classes dObject supports three types of numeric classes: Int, Long, and Real. Class Int supports signed 2-byte integer values between -32,768 to 32,767. Long values are signed 4-byte integer numbers in the range -2147483648 to 2147483647. Real numbers are 8 bytes long and in the range -1e+307 to 1e+308. dObject provides operators for performing arithmetic on Int, Long and Real classes. For example, to add two integers together to get a third, send the "plus" message to the first integer, using the second integer as an argument. This is accomplished in the statement: dObject> n = 1+2; dObject> ? n; 3 where the variable "n" will be assigned the value Int 3. dObject responds to the '+' (plus), '-' (minus), '*' (multiply), and '/' (divide) operators on both Int and Real variables. Mixed mode arithmetic is also supported for calculations involving Ints and Reals, in which case the result is always Real. Mixed mode arithmetic involving Long values is not supported. A wide variety of named messages are supplied for numeric classes, including: * max(self,Int), max(self,Real), max(self,Long) - returns max value of self and arg * min(self,Int), min(self,Real), min(self,Long) - returns min value of self and arg * abs(self) - returns absolute value of self (Int or Real) * log(self) - returns log base e of self (Real) * log10(self) - returns log base 10 of self (Real) * sqrt(self) - returns square root of self(Real) - 27 - dObject Version 1.0 (c) 1991 Intelligent Systems Research * sin(self) - returns sine of self (Real, self in radians) * cos(self) - returns cosine of self(Real, self in radians) * tan(self) - returns tangent of self (Real, self in radians) Refer to the accompanying file "CLASSLIB.DOC" for a complete description of the built-in numeric methods and operators. Of course, you can define new methods for the numeric classes if you so choose. This example show defining a new method "factorial" for the Long class, which calls itself recursively: /* define a recursive factorial method for the "Long" class */ method Long::factorial(self) { if(self <= 1L) return(self); else return(self*factorial(self-1L)); } /* calculate some factorials */ i = 0; while(i < 10) { ? i," ",factorial(asLong(i)); i = i+1; } 6.0 Logical Operations 6.1 Logical Operations dObject provides the built-in class "Logical" for representing the boolean values of "true" and "false". dObject also provides built-in operators for a variety of comparison operations between classes that result in a Logical value: OPERATOR NAME CLASS(ES) DESCRIPTION [eq][eq] equal all returns true if self and arg are equal != not equal all returns true if self and arg are not equal - 28 - Chapter 6: Logical Operations > greater than Int,Real,Char,String returns true if self greater than arg >= greater than/eqInt,Real,Char,String returns true if self greater than or equal to arg < less than Int,Real,Char,String returns true if self less than arg <= less than/eq Int,Real,Char,String returns true if self less than or equal to arg To create a logical value, use the "new" method, a literal Logical value, or make an assignment using one of the comparison operators above: dObject> l = new(Logical); dObject> l = T; dObject> l = 1 < 2; 7.0 Characters and Strings 7.1 Characters and Strings dObject provides the built-in classes "Char" and "String" for handling character calculations. A Char literal should be a single character surrounded by single quotes, while a String literal can be any number of characters delimited by the double quote character. To create a string, use the "new" method or make an assignment using a literal: dObject> s = new(String); dObject> s2 = "this is a string"; To find the length of a String, use the "len" method: dObject> ? len(String); 16 Strings respond to the normal set of comparison operators (==,!=, <, <=,>, >=). Trailing blanks can be removed from a String by the "trim" method: dObject> ? len(trim("aaa ")); 3 - 29 - dObject Version 1.0 (c) 1991 Intelligent Systems Research Strings can be concatenated together using the "+" operator: dObject> a = "string1"; dObject> b = "string2"; dObject> ? a + " and " + b; "string1 and string2" To access a particular character in a String, use the "at" method: dObject> c = at("test",2); dObject> ? c; e The same built-in text editor that is used by the "edit" command to edit text files is callable as a method of the String class. This causes the contents of the string to be edited in the current window, and returns the value of the edited string. For a read-only display of the string contents in the current window with no editing allowed, use the "display" method: dObject> s = "this is a string"; dObject> edited_string = edit(s); dObject> display(edited_string); dObject also provides String methods to interface directly with DOS. A DOS command within a String can be executed using the "system" method, passing it the command string in the "self" argument and an Int indicator for resetting the screen to the state it was in prior to executing the command string (0=do not reset, 1=reset): dObject> cmd = "dir *.do"; dObject> system(cmd,0); The value of a DOS environment variable can be accessed through the "envSymbol" method: dObject> s = envSymbol("path"); A named file can be edited using the "editFile" method: dObject> editFile("test.txt"); The contents of an existing DOS file can be placed in a String very quickly by the "fileString" method, where "self" is the name of the file: - 30 - Chapter 7: Characters and Strings dObject> text = fileString("test.do"); dObject> edit(text); String values can be converted to Int, Real, Date, and Logical values using the "asInt", "asReal", "asDate", and "asLogical" methods respectively: dObject> s = "123"; dObject> ? class(asInt(s))," ",asInt(s); Int 123 String values can be forced to upper or lower case using the "asUpper" and "asLower" methods: dObject> s = "This is a Test"; dObject> ? asUpper(s); THIS IS A TEST dObject> ? asLower(s) this is a test dObject provides a pattern match function in the String::match() method. This method matches a pattern against the string and returns a Int index specifying the portion of the string that matched the pattern: dObject> s = "This is a test"; dObject> ? match(s,"is a test"); 6 The special codes recogized by the String::match() method are those recognized by the UNIX GREP utility and include: * ' start-of-line anchor * '$' end-of-line anchor * '.' matches any character * '[' start a character class * ']' end a character class * ' negates character class if 1st char * '*' Keene closure (matches 0 or more) * '+' positive closure (1 or more) - 31 - dObject Version 1.0 (c) 1991 Intelligent Systems Research * '?' optional closure (0 or more) There are other String methods provided by dObject that are described in CLASSLIB.DOC. 8.0 Dates 8.1 Dates dObject provides a rich set of methods for handling dates using the built-in "Date" class. To create a new date variable, use the "new" method, or a date literal: dObject> d = new(Date); dObject> d = 5/1/91; The built in Nil::date() method returns the current system date as a Date variable. You can access the month, day, and year parts of a date using the "month", "day", "year", and "century" methods. For example, the expression below will return just the year of the current date as an Int: dObject> ? year(date()); You can also set the values of these parts of the date using the "setMonth", "setDay", "setYear", and "setCentury" methods: dObject> d = date(); dObject> d = setMonth(d,1); dObject supports the addition and subtraction of an integer number of days to and from a Date variable, and also supports conversion of Dates to a julian value. For example, to find the date that is 30 days from the current date: dObject> future_date = date()+30; The "asJulian" method returns a Real value that is the julian date for a Date value. The Real::asDate method performs the inverse operation, returning a Date for a given julian number: dObject> j = asJulian(date()); dObject> d = asDate(j); - 32 - Chapter 8: Dates Dates can be formatted into and from String variables in a variety of formats, including international formats. dObject provides the "asString" method for the Date class and the "asDate" method for the String class to accomplish these format conversions. In both cases a format String is passed to the method indicating how the date is to be formatted or scanned: /* test the dObject date conversion functions */ ? date(); s = asString(date(),"MMM DD/YY"); ? s; d = asDate(s,"MMM DD/YY"); ? d; The valid date format codes recognized by dObject are: * CC 2-digit century * YY 2-digit year * MM 2-digit month * MMM 3-char month (JAN, FEB, etc.) * DD 2-digit day These codes can be used in format strings to indicate how the date should be formatted or scanned. For example, the following are typical date formats: * YY.MM.DD * CCYY.MM.DD * MM/DD/YY * DD-MM/YY * DD-MM/CCYY * MMM DD/YY As a final example, the following code implements the "cday" method, which returns a String that contains the name of the day for the date: /* this is an example of how to define methods for the built-in Date class - 33 - dObject Version 1.0 (c) 1991 Intelligent Systems Research "cday" returns a character string naming the day */ method Date::cday(self) { if(dow(self) == 1) return("Sunday"); if(dow(self) == 2) return("Monday"); if(dow(self) == 3) return("Tuesday"); if(dow(self) == 4) return("Wednesday"); if(dow(self) == 4) return("Thursday"); if(dow(self) == 5) return("Friday"); if(dow(self) == 6) return("Saturday"); } /* define the same function, using the "switch" statement */ method Date::cday2(self) { switch(dow(self)) { case 1: return("Sunday"); case 2: return("Monday"); case 3: return("Tuesday"); case 4: return("Wednesday"); case 5: return("Thursday"); case 6: return("Friday"); case 7: return("Saturday"); } } /* call the methods defined above */ ? cday(date()); ? cday2(date()); 9.0 Windows and Menus dObject provides classes that allow you to write professional-looking applications that use character-cell windows and pop-up menus. The "?" command, the "say" method of the Window class, and the built-in "Field" base class all send their output to a specified window. 9.1 Windows Windows are created using the "new" method, and passing it the window number, window attribute, frame attribute, title, left corner y,x position, and the y and x lengths for the window as parameters. The x,y co-ordinates of a window or other object within a window are - 34 - Chapter 9: Windows and Menus always counted down and right from the (0,0) origin in the upper left corner. For example, to create a new window that is the size of the entire screen, contains the title "test window", and has a white on blue display color and a lite blue border: dObject> w = new(Window,1,31,3,"test window",0,0,24,80); Color attributes can be calculated from the following formula: * Choose one foreground color and one background color * Add the corresponding integer values below. * Add 128 if you want whatever is displayed with that attribute to blink BACKGROUND FOREGROUND Black 0 Black 0 Blue 16 Blue 1 Green 32 Green 2 Cyan 48 Cyan 3 Red 64 Red 4 Magenta 80 Magenta 5 Brown 96 Brown 6 White 112 White 7 Grey 8 Light Blue 24 Light Green 40 Light Red 72 Light Magenta 88 Yellow 104 White (High 120 Intensity) You can also include the supplied file "COLORS.DO" that defines symbolic names for the colors. When the "new" method creates the window it also displays it immediately and makes the new window the current window. To write output to a window, you must first make the window current. You can do this explicitly by sending the window the "shiftwindow" message: dObject> shiftwindow(w); You can always obtain the current window as a Window object through a call to the Nil::currentWindow() method: dObject> shiftwindow(currentWindow()); - 35 - dObject Version 1.0 (c) 1991 Intelligent Systems Research You can clear the contents of a window with the "clear" message. To remove a window from the screen, send it the "remove" message: dObject> remove(w); To interactively resize or setup the color for a window, use the "resize" and "setupColor" methods. These methods allow for interactive resizing and color setup using the cursor keys and a color display that shows the foreground and background colors available as well as the color attribute number. When interactively resizing a window, use the following keys to change the window's size: * Width - Press the left arrow key to make the window narrower or the right arrow key to make it wider. To make changes in larger increments, hold down the Ctrl key at the same time. Use the end key to expand the window at the start of the screen. * Length - Press the up arrow key to decrease or the down arrow key to increase the length of the window. Use the page down key to extend the window to the bottom of the screen and the page up key to extend the window to the top of the screen. To change the position of the window on the screen, use the following keys: * Shift-Up Up one row * Shift-Down Down one row * Shift-Right Right one column * Shift-left Left one column * Shift-Home To left screen edge * Shift-End To right screen edge * Shift-PgUp To top of screen * Shift-PgDn To bottom of screen * Ctrl-Home To top left screen corner * Ctrl-End To bottom left screen corner * Ctrl-PgUp To top right screen corner - 36 - Chapter 9: Windows and Menus * Ctrl-PgDn To bottom right screen corner To setup the color for the window text, pass the setupColor method an Int argument of 0; to setup the color of the frame, pass it an Int argument of 1. For example, the following statement invokes the setup display for the color of the current window: dObject> setupColor(currentWindow(),0); dObject creates windows with a default frame consisting of a single-width line border, and with the window title centered above the window in the border. to change this, you can use the "setFrame" message. The first argument to setFrame is the color attribute of the frame, followed by the title of the frame, the integer position to place the title counting from the left-hand side (a value of 0 instructs dObject to center the title), and finally a String containing 6 characters to build frame with using the following convention: * 1st char: Upper left corner * 2nd char: Upper right corner * 3rd char: Lower left corner * 4th char: Lower right corner * 5th char: Horizontal line * 6th char: Vertical line For example, to frame a window with the title "My Window" starting at position 3, with a white frame and a the '#' character for a border, use the message: dObject> setFrame(w,7,"My Window",3,"######"); 9.2 Output using SAY and GET dObject provides methods to build full-screen data entry and review forms through the Int::say() and Window::say() methods, and through the built-in Field base class. The SAY/GET facility in dObject is similar in function to the @ say and @ get commands provided by the DBASE language. In dObject these methods work within a window, providing a way to create very sophisticated data handling forms. To produce output from an expression at a y,x point within a window, send the window the Int y coordinate, the Int x coordinate, the expression to output, an Int length of the field to display, and an - 37 - dObject Version 1.0 (c) 1991 Intelligent Systems Research Int color attribute to display the expression in: dObject> say(currentWindow(),5,5,"this is a test",14,7); To set up a get field for input, call the Exp::new method for the class "Field", and send it the Window to place the field in, the Int y coordinate, the Int x coordinate, a String name of the variable to place the result into, an Int length of the field to display, and Int color attribute. Make sure that the variable you will store the value into is already defined: dObject> a = "this is a test"; dObject> new(Field,currentWindow(),6,6,"a",14,112); Alternatively, the field name can be the name of a DBASE field in the currently active DBF file: dObject> db = new(Dbffile,"patient"); dObject> new(Field,currentWindow(),6,6,"lname",14,112); The Exp::new(Field,...) method returns a variable of type Field that represents the field within the window. Once defined, a list of get variables can be read in a full-screen input mode using the Window::read() method: dObject> read(currentWindow()); Entering this mode causes dObject to position the cursor at the beginning of the first get field defined, and to wait for the user to enter new values for data fields and scroll through records in the current Dbffile. The specific keys recognized are: KEY ACTION DESCRIPTION Esc Escape exits the form and returns to dObject> prompt Home Goto top Positions the current DBF file at the first record and displays it End Goto bottom Positions the current DBF file at the last record and displays it PgUp Prev Record Positions the current DBF file at the previous record and displays it PgDn Next Record Positions the current DBF file at the next record and displays it Tab Next Field Positions the cursor at the beginning of the next display field Up Up cursor Positions the cursor up one line - 38 - Chapter 9: Windows and Menus Down Down cursor Positions the cursor down one line Right Right cursor Positions the cursor right one space within current display field Left Left cursor Positions the cursor left one space within the current display field F10 Quit exits the form and returns to dObject> prompt You can modify the actions associated with these or any other key while in read mode by calling the Int::onKey() method and passing it an expression to evaluate. For example, the following example shows how to call the built-in text editor to edit the contents of a GET field by pressing the F8 key while in read mode: /* this method implements a callable text editor for the contents of a field */ method Window::myEdit(self) { f = currentField(self); s = eval(asId(name(f))); if(class(s) == "String") { w = new(Window,1,31,3,name(f),5,5,10,40); display(s); remove(w); gotoField(self,f); } } db = new(Dbffile,"patient"); new(Field,currentWindow(),6,6,"lname",14,112); onKey(w,F8,#myEdit(w)); read(currentWindow()); To clear the existing list of get variables from future reads, use the Window::clearGets() method: dObject> clearGets(currentWindow()); The following example program shows setting up two get fields with prompts: /* sample full screen field output */ w = new(Window,1,31,3,"",0,0,24,80); clearGets(2); a = "test"; - 39 - dObject Version 1.0 (c) 1991 Intelligent Systems Research b = "test2"; say(w,5,5,"field a",7,7); say(w,6,5,"field b",7,7); new(Field,w,5,20,"a",10,112); new(Field,w,6,20,"b",10,112); read(w); remove(w); 9.3 Pictures You can assign a picture template to a GET field that will cause dObject to format the value being displayed in the field, and validate keystrokes upon entry to the field. Do this by calling the Field::setPicture() method, and passing it a String containing the picture: dObject> a = "test"; dObject> f = new(Field,w,5,20,"a",10,112); dObject> setPicture(f,"!!!!!!!!!!"); dObject recognizes the following picture code characters: * ! - Converts letters to uppercase; accepts all characters * A - Allows letters only * L - Translates characters to logical values (T, t, F, f, Y, y, N, n) * N - Allows letters and numbers * 9 - Allows digits only * X - Allows numbers, spaces, signs, and decimal points only * Other characters are copied literally into the displayed value The following example demonstrates the use of picture clauses: /* demonstrate the use of a picture within a GET field */ w = currentWindow(); clearGets(w); cls; - 40 - Chapter 9: Windows and Menus a = "test"; prompt = "Enter a value: "; say(w,5,5,prompt,len(prompt),7); f = new(Field,w,5,len(prompt)+5,"a",10,112); setPicture(f,"!!!!!!!!!!"); read(w); ? "the value you entered was ",a; 9.4 Key Codes The special key codes recognized by the Window::read() and Nil::inkey() methods are defined in the supplied file KEYDEF.DO (you can include this file in programs by using the #include preprocessor statement): #define BACK_SPACE "$08" #define TAB "$09" #define ESC "$1B" #define CTRL_A "$01" #define CTRL_B "$02" #define CTRL_C "$03" #define CTRL_D "$04" #define CTRL_E "$05" #define CTRL_F "$06" #define CTRL_G "$07" #define CTRL_H "$08" #define CTRL_I "$09" #define CTRL_J "$0A" #define CTRL_K "$0B" #define CTRL_L "$0C" #define CTRL_M "$0D" #define CTRL_N "$0E" #define CTRL_O "$0F" #define CTRL_P "$10" #define CTRL_Q "$11" #define CTRL_R "$12" #define CTRL_S "$13" #define CTRL_T "$14" #define CTRL_U "$15" #define CTRL_V "$16" #define CTRL_W "$17" #define CTRL_X "$18" #define CTRL_Y "$19" #define CTRL_Z "$1A" #define RETURN "$D" #define HOME "$4700" #define END "$4F00" #define PGUP "$4900" #define PGDN "$5100" #define UP "$4800" #define DOWN "$5000" - 41 - dObject Version 1.0 (c) 1991 Intelligent Systems Research #define RIGHT "$4D00" #define LEFT "$4B00" #define SHIFT_TAB "$0F00" #define INS "$5200" #define DEL "$5300" #define CTRL_HOME "$7700" #define CTRL_END "$7500" #define CTRL_PGUP "$8400" #define CTRL_PGDN "$7600" #define CTRL_RIGHT "$7400" #define CTRL_LEFT "$7300" #define ALT_1 "$7800" #define ALT_2 "$7900" #define ALT_3 "$7A00" #define ALT_4 "$7B00" #define ALT_5 "$7C00" #define ALT_6 "$7D00" #define ALT_7 "$7E00" #define ALT_8 "$7F00" #define ALT_9 "$8000" #define ALT_0 "$8100" #define ALT_MINUS "$8200" #define ALT_EQUAL "$8300" #define ALT_Q "$1000" #define ALT_W "$1100" #define ALT_E "$1200" #define ALT_R "$1300" #define ALT_T "$1400" #define ALT_Y "$1500" #define ALT_U "$1600" #define ALT_I "$1700" #define ALT_O "$1800" #define ALT_P "$1900" #define ALT_A "$1E00" #define ALT_S "$1F00" #define ALT_D "$2000" #define ALT_F "$2100" #define ALT_G "$2200" #define ALT_H "$2300" #define ALT_J "$2400" #define ALT_K "$2500" #define ALT_L "$2600" #define ALT_Z "$2C00" #define ALT_X "$2D00" #define ALT_C "$2E00" #define ALT_V "$2F00" #define ALT_B "$3000" - 42 - Chapter 9: Windows and Menus #define ALT_N "$3100" #define ALT_M "$3200" #define F1 "$3B00" #define F2 "$3C00" #define F3 "$3D00" #define F4 "$3E00" #define F5 "$3F00" #define F6 "$4000" #define F7 "$4100" #define F8 "$4200" #define F9 "$4300" #define F10 "$4400" #define CTRL_F1 "$5E00" #define CTRL_F2 "$5F00" #define CTRL_F3 "$6000" #define CTRL_F4 "$6100" #define CTRL_F5 "$6200" #define CTRL_F6 "$6300" #define CTRL_F7 "$6400" #define CTRL_F8 "$6500" #define CTRL_F9 "$6600" #define CTRL_F10 "$6700" #define SHIFT_F1 "$5400" #define SHIFT_F2 "$5500" #define SHIFT_F3 "$5600" #define SHIFT_F4 "$5700" #define SHIFT_F5 "$5800" #define SHIFT_F6 "$5900" #define SHIFT_F7 "$5A00" #define SHIFT_F8 "$5B00" #define SHIFT_F9 "$5C00" #define SHIFT_F10 "$5D00" #define ALT_F1 "$6800" #define ALT_F2 "$6900" #define ALT_F3 "$6A00" #define ALT_F4 "$6B00" #define ALT_F5 "$6C00" #define ALT_F6 "$6D00" #define ALT_F7 "$6E00" #define ALT_F8 "$6F00" #define ALT_F9 "$7000" #define ALT_F10 "$7100" 9.5 Menus - 43 - dObject Version 1.0 (c) 1991 Intelligent Systems Research dObject provides a pop-up menu facility in the built-in Menu and Linemenu classes. Menus are created by passing the "new" method the Int y,x location of the upper left corner of the menu, the Int length of the menu (number of lines to show), the Int text and frame color attributes, a Collection of menu choices, and a String title. Menus are executed using the "choice" method containing an Int argument that specifies what choice to highlight upon entry to the menu. The "choice" method returns the index of the menu item chosen within the Collection; the calling program can retrieve the actual value chosen by indexing the Collection with the "at" method. Menus remain displayed in the current Window until the "remove" message is sent to them. The following example shows putting up a menu of numeric values and asking the user to choose: /* create a menu using a Collection of choices */ myCollection = [1.0,2.0,3,4,5,6,7,8,9]; a= new(Menu,3,3,5,31,3,myCollection," test "); b = choice(a,1); remove(a); ? "result of menu is ",b; /* the actual value chosen is found by getting the value in the collection at index "b" */ value = at(myCollection,b); To exit the menu without making a choice, press the ESC key while the menu is active. This causes the Menu::choice() method to return 0 as the chosen value. The number of values in the Collection in a Menu can be much larger than the display size of the Menu. When this occurs, the user can press the up and down arrow keys to scroll through the menu before making a choice with the "Enter" key. 9.6 Line Menus dObject also provides a "Linemenu" class that implements lotus-style line menus with optional help lines. You can create a line menu using the "new" method, and passing it the Int window number of the window to create for the menu, an Int row and column for the upper left corner of the menu, an Int width of the menu, a Collection of values to put in the menu, and a corresponding Collection of status lines to show for each menu choice. When the menu is created and - 44 - Chapter 9: Windows and Menus shown using the Linemenu::choice() method, the choices will be evenly spaced across the width of the menu in the first line of the menu, and the status line text for a given choice will be displayed on the second line, much like the style of a Lotus 1-2-3 menu. The following example illustrates the use of the Linemenu class: /* demo of the Linemenu class */ color = 54; width = 40; m = new(Linemenu,1,5,width,color,color,[1,2,3,4,5,6], ["first","second","third","fourth","fifth","sixth"]); c = choice(m); remove(m); ? "your choice was ",c; You can create a Linemenu that does not display status lines underneath the choices by passing an empty Collection to "new" for the status line text. In this case a one-line menu will be created: m = new(Linemenu,1,5,5,54,54,[1,2,3,4,5,6],[]); 9.7 Hypertext dObject provides the capability to use the Window class described above to display hypertext built from DBASE data and index files. To build a hypertext string that can be displayed or edited using the built-in text editor, use the Dbffile::htExpand() method. The "self" argument to this method is a Dbffile object that contains at least two text fields: one field containing a one-word topic string, and one field containing the text to show whenever that topic is selected from within a display. For example, the supplied dObject files HELP.DBF, HELP.DBT, and HELP.NDX are DBASE files that are used as the dictionary for the on-line help within the text editor and are an example of suitable hypertext files: dObject> db = new(Dbffile,"help"); dObject> displayStructure(db); Structure for: HELP.DBF Number of records: 8 Last update: 6/2/91 Version: 3 Number of fields: 2 Field Field Name Type Width Dec 0 TOPIC C 8 0 1 TEXT M 10 0 - 45 - dObject Version 1.0 (c) 1991 Intelligent Systems Research You must also pass an Ndxfile object that is a DBASE index on the topic field, a String name of the text field to use in the Dbffile for the text to show for a topic, an Int color to highlight the words in the string being converted that have topic entries in the Dbffile, and a String containing the text to convert. The method returns a String containing embedded control codes telling the built-in editor to highlight the topic words in the color you have chosen. The following example illustrates the proper calling sequence: dObject> db = new(Dbffile,"help"); dObject> ndx = useIndex(db,"help"); dObject> keylen = 32; % length of the topic field dObject> htext = htExpand(db,ndx,"text",31,keylen, "this is some text"); To display the hypertext within the current window, use the String::display() method: dObject> display(htext); Calling this method will display the text within the current window with words that have matching entries in the topic field of the Dbffile highlighted with the color attribute chosen above. You can position the cursor using the normal editor keys, and you can "follow" the hypertext link for a highlighed word by positioning the cursor on that word and pressing the CTRL-F1 key. Pressing this key causes dObject to execute the String::onHyperKey() method with the contents of the "text" field for the topic that was found in the Dbffile. You should always supply a version of String::onHyperKey as part of your hypertext application; If you do not, pressing the CTRL-F1 key will have no effect will look for the word at the cursor in the HELP.DBF file. The following example shows how to define the String::onHyperKey() method and build a small hypertext application using the supplied dObject HELP.DBF, HELP.NDX, and HELP.DBT files: /* this is a demo of dObject's hypertext display feature first, define a method to handle the "follow hyper link" key when it is pressed from a window */ method String::onHyperKey(self) { /* create a window for the text */ w = new(Window,1,31,31,"",8,8,10,40); /* - 46 - Chapter 9: Windows and Menus the color attribute is the first character token in the string */ color = asInt(token(self,#s)); /* turn off the dObject hypertext help key (CTRL-F1) from within the display */ set("hyperhelp",F); /* display the text to follow the link for a highlighted field, hit the SHIFT-F8 key */ display(htExpand(db,index,"text",32,color,s)); remove(w); } /* demo hypertext */ #define COLOR 79 db = new(Dbffile,"help"); index = useIndex(db,"help"); w = new(Window,1,31,31," Hypertext ",5,5,10,50); display(htExpand(db,index,"text",COLOR,32,":while for if then else dos")); remove(w); close(db); 10.0 Arrays and Collections 10.1 Arrays dObject provides classes for handling Arrays and Collections of objects. The primary difference between an Array and a Collection is that a Collection can be considered an ordered list of values that can easily be inserted into, appended to , and deleted from, while an Array is similar to a DBASE array that can be easily indexed by a set of integer indexes, but not easily ordered, inserted into, or deleted from. Both Collections and Arrays can contain any kind of dObject class, including other Collections and Arrays. There is no pre-defined limit on the size of an Array or Collection, but attempts to use more memory than is available will cause an error message. Arrays are similar to those provided in the DBASE programming language. An array element can be stored or retrieved from a specific location within an array through the use of the "replace" and "at" messages, passing a Collection of integer indexes as an argument. - 47 - dObject Version 1.0 (c) 1991 Intelligent Systems Research For example, to create an array of 10 elements and store a String value in the first location: dObject> a = new(Array,[10]); dObject> replace(a,[1],"this is the first element"); dObject> ? at(a,[1]); t To create multi-dimensional arrays, create the array with more than one dimension in the dimension Collection, and address it with more than one element in the index Collection: dObject> a = new(Array,[3,3,3]); dObject> replace(a,[1,1,1],"this is the first element"); /* this is a test of dObject's Array class */ method Array::print(self) { i = 0; while(i < len(self)) { print(at(self,i)); print(' '); i = i+1; } } /* create a single-dimension array of 4096 locations */ a = new(Array,[4096]); i = 0; while(i < 4096) { replace(a,[i],i); i = i+1; } ? a; 10.2 Collections dObject's Collection class provides an advanced way to store ordered collections of objects. The Collection class comes with a comprehensive set of built-in methods for adding, deleting, finding, and replacing members within the collection. Collections are most easily created using the literal convention of surrounding a comma-separated list of literal values with brackets: dObject> myCollection = [1,2,3,4,5]; - 48 - Chapter 10: Arrays and Collections Empty Collections can also be created using the Exp::new() method: dObject> myCollection = new(Collection); dObject> ? myCollection; [] As with Arrays, members of a Collection can be any valid dObject class, including other Collections: dObject> myCollection = [[1,2,3],[4,5,6],[7,8,9]]; To add a value to the end of a Collection, use the "append" method: dObject> myCollection = [1,2,3]; dObject> myCollection = append(myCollection,4); dObject> ? myCollection; [1,2,3,4] To replace an existing value within a Collection, use the "replace" method, passing it a value to replace and the new value to replace it with: dObject> myCollection = [1,2,3]; dObject> myCollection = replace(myCollection,1,32); dObject> ? myCollection; [32,2,3] The number of values within a Collection can be found by the "len" method: dObject> ? len([1,2,3,4,5]); 5 The first value in a Collection is called the "head" of the Collection, and the remaining Collection without the head is called the "tail": dObject> ? myCollection = [1,2,3]; dObject> ? head(myCollection); 1 dObject> ? tail(myCollection); [2,3] - 49 - dObject Version 1.0 (c) 1991 Intelligent Systems Research Individual values within a Collection can be retrieved using an Int index, but this is not nearly as efficient as using an Array for this purpose: dObject> ? at(["one","two","three"],2); two The last element in a collection is available using the "last" method: dObject> ? last([1,2,3,4]); 4 The maximum and minimum values from within a Collection can be found with the "max" and "min" methods respectively: dObject> ? max([1,2,3]); 3 A Collection can be filtered into another Collection by the "sort" and "unique" methods. The "sort" method returns a Collection that is the sorted version of the variable it is called on. The sort is accomplished using the ">" operator on whatever class is in the Collection, and is done in ascending order: dObject> ? sort([3,1,4,6,5,2]); [1,2,3,4,5,6] The "unique" method returns a Collection consisting of the unique elements in the Collection it is called on: dObject> ? unique([1,1,2,2,3,3,4,4,5,5,6,6]); [1,2,3,4,5,6] The following example demonstrates many of the methods available for handling Collections: /* this is a demonstration of dObject's Collection class */ a = [5,3,9,5,100,44,5]; ? "Collection is ",a; ? "length is ",len(a); ? "reversed is ",reverse(a); ? "third element is ",at(a,3); ? "last element is ",last(a); ? "with 100 removed is ",remove(a,100); - 50 - Chapter 10: Arrays and Collections ? "substitute 1005 for 5 is ",replace(a,5,1005); ? "is 44 in collection ?: ",44 $ a; ? "sorted array is ",sort(a); ? "unique array is ",unique(a); ? "unique sorted Collection is ",sort(unique(a)); ? "sum of elements is ",sum(a); ? "minimum value is ",min(a); ? "maximum value is ",max(a); ? "average value is ",avg(a); /* fill a collection */ a = []; i = 0; while(i < 10) { a = append(a,i); i = i+1; } ? a; 11.0 Files and Devices 11.1 Files and Devices dObject allows output to DOS text files and to devices such as the printer through the built-in "File" class. Files are created by passing the "new" method the name of the file to create, an Int switch indicating if the file is to be opened in read, write, or append mode (1,2, or 3 respectively), an Int containing the DOS attributes of the file, and an Int specifying what to do if the file already exists: dObject> f = new(File,"new.out",1,0,0); Constant definitions for the open mode, the DOS file attributes, and the creation option flag are provided in the file IODEF.DO: /* some constant definitions for new(File,...) */ /* File Attributes */ #define FA_RDONLY "$01" /* Read only file */ #define FA_HIDDEN "$02" /* Hidden file */ #define FA_SYSTEM "$04" /* System file */ #define FA_SUBDIR "$10" /* Subdirectory */ #define FA_ARCH "$20" /* Archive file */ #define FA_NORMAL "$40" /* Normal file - No read/write restrictions */ - 51 - dObject Version 1.0 (c) 1991 Intelligent Systems Research /* File usage Modes */ #define FM_ACCESS_WO "$0001" /* write only */ #define FM_ACCESS_RW "$0002" /* read/write */ #define FM_ACCESS_RO "$0004" /* read only */ #define FM_SH_DENYRW "$0010" /* deny read/write mode */ #define FM_SH_DENYWR "$0020" /* deny write mode */ #define FM_SH_DENYRD "$0030" /* deny read mode */ #define FM_SH_DENYNO "$0040" /* deny none mode */ /* Exclusively for OS2 and DOS >4.0 */ #define FM_RETURNERR "$2000" /* return error rather than call crit hand. */ #define FM_WRITETHRU "$4000" /* write through */ /* Creation Flags */ /* Actions if file exists (low nibble) : */ #define CR_EX_FAIL "$00" #define CR_EX_OPEN "$01" #define CR_EX_REPLACE "$02" /* Actions if file doesn't exist (high nibble): */ #define CR_NOEX_FAIL "$00" #define CR_NOEX_CREATE "$10" dObject maintains "current" input and output devices which are normally the keyboard and the screen respectively. These devices can be redirected to files through the "readDevice" and "writeDevice" methods: dObject> writeDevice(f); Files can be flushed and closed through the "flush" and "close" methods. For example, to open a file and write a line of output to it: You can read a character from the current input device using the Nil::readchar() method, which returns the next character as a Char variable. To read a complete keycode from the keyboard as an Int, use the Nil::inkey() method. The key definitions returned by Nil::inkey() are defined in the include file "keydef.do". If you use Nil::readchar() to read characters, you can "push back" characters into the input buffer using the Char::unread() method. This method pushes its Char argument back into the input buffer where it can be read later using Nil::readchar(). The following example describes how to create a file and write output to it: - 52 - Chapter 11: Files and Devices /* this is a demonstration of dObject's file handling capabilities */ f = new(File,"new.out",1,0,0); writeDevice(f); ? "this is a test"; close(f); When opening a file in the "new" command, the filename can also be a device name, such as "prn:". The printer can be accessed as shown in the following example: /* this is a demonstration of dObject's printer handling features open the printer and print 10 lines to it without echoing the lines to the screen */ p = new(File,"prn:",1,0,0); writeDevice(p); i = 1; while(i < 10) { ? "printing line ",i; i = i+1; } /* note: on some printers (HP II, Epson EPL-6000) it is necessary to send an ESC E to flush the printer... consult your printer manual to see if the next line is necessary, otherwise the "flush" method should work OK by itself */ ? chr(27),'E'; flush(p); close(p); ? "printout is done"; 12.0 DBASE File Programming 12.1 DBASE File Programming dObject provides an extensive set of built-in methods for handling DBASE data, memo, and index files. You can create your own new DBASE-format files for storing data, or use existing files already in the DBASE format. You can also use and create DBASE index (.NDX) files. - 53 - dObject Version 1.0 (c) 1991 Intelligent Systems Research 12.2 Creating DBASE Files The following example demonstrates how to create a .DBF file using the String::createDbf() method. The argument to "createDbf" is an Collection of Collections of field defintions. Each field definition Collection should contain a string that is the DBASE field name, a character field type ('C' = char, 'N' = numeric, 'D' = date, 'M' = memo), an Int length, and an Int number of decimals for numerics: /* create a new Dbffile */ db = createDbf("test",[ ["cfield",'C',32,0], ["nfield",'N',5,0], ["dfield",'D',0,0], ["mfield",'M',512,0]); displayStructure(db); dObject will create a .DBT file for each MEMO field specified in the Collection of field definitions. To set the value of a field within the current DBASE file, set a variable with the same name as the field to a value, just like in DBASE. Once set, the field value can be updated in the current record by the "write" method, or a new record can be appended to the file using the "write" method: /* store some test data to the database */ select(db); % make sure the Dbffile to process is the "current" file i = 1; while(i < 10) { cfield = "test"+asString(i); nfield = i; dfield = date(); mfield = "memo" + asString(i); write(db,0L); i = i+1; } The structure (field definitions) from a DBF file can be obtained by using the Dbffile::structure() method. This returns a Collection of field definitions like the one described above. The following is an example of how to use the structure method to simulate some common DBASE commands: - 54 - Chapter 12: DBASE File Programming /* Dbffile::copyStructure(self,newname) this method copys the structure of self to a new database with name of "newname" only the structure of self is copied; no records are copied */ method Dbffile::copyStructure(self,newname) { l = structure(self); createDbf(newname,l); } /* Dbffile::list(self) this method lists the records in a Dbffile to the screen */ method Dbffile::list(self) { top(self); fields = structure(self); newline = set("newline"); set("newline",""); while(!eof(self)) { for(i=1;i<numFields(self);i=i+1) { f = at(fields,i); name = at(f,1); ? eval(asId(name))," "; } ? "\n"; skip(self,1L); } set("newline",newline); } dObject> db2 = copyStructure(db,"test2"); 12.3 Reading DBASE Files DBF files can be opened through the use of the "new" message with the name of the DBF file passed as an argument. Once opened, the records and fields within a DBF file are available for reading and for update by your dObject program. For example, to open the "patient.dbf" file, use the statement: dObject> db = new(Dbffile,"patient"); The number of records and fields defined within a DBF file are available through calls to the "numRecords" and "numFields" methods: - 55 - dObject Version 1.0 (c) 1991 Intelligent Systems Research dObject> ? numFields(db); 6 dObject> ? numRecords(db); 20 The current record number is available as a Long using the "recno" method: dObject> top(db); dObject> ? recno(db),class(recno(db)); 1 Long Dbffiles can be positioned by sending them the "top", "bot", "locate", and "seek" messages. The "eof" method returns logical T when a Dbffile is positioned beyond the last record in the file (and otherwise returns logical F). The following example demonstrates a program that loops over all the records in a DBF file: db = new(Dbffile,"patient"); top(db); while(!eof(dbf)) { ? "at record ",recno(db); skip(db,1L); } The "locate" method can be used to locate specific field values of type Int, Real, Char, String, Date, or Logical. The first argument to the method should be the name of the field to perform the comparison on, and the second the value to find. The search will always start at the current record, so to always search from the top of the database, the "top" method can be used to position the Dbffile first: dObject> db = new(Dbffile,"patient"); dObject> locate(top(db),"lname","lname6"); Fields within DBF files are accessed by using a variable name with the same name as a field in the currently selected database, as in DBASE: dObject> db = new(Dbffile,"patient"); dObject> top(db); dObject> ? lname; lname0 dObject> select(db); - 56 - Chapter 12: DBASE File Programming The currently selected Dbffile is available through a call to the Nil::currentDbffile() method: dObject> top(currentDbffile()); You can also perform sophisticated calculations over all the records in a DBASE file using the built-in "sum", "max", "min", and "avg" methods. These methods accept a literal dObject expression as an argument, and evaluate the sum, max, min, or average of the expression over all the records in the file. For example, to calculate the minimum and maximum length of a DBASE char field named "lname", your need to evaluate the length of the trimmed field value across all the records in the file. The following commands perform this task: dObject> ? db = new(Dbffile,"patient"); dObject> ? min(db,#len(trim(lname))); dObject> ? max(db,#len(trim(lname))); These methods always start from the top of the file. 12.4 Using Filters dObject allows you to specify an expression as a "filter" for a .DBF file to make it appear to your application that certain records do not exist. The expression is evaluated for each record within a .DBF file, and unless the expression evaluates to logical true for a given record, the record appears as if it does not exist. To create an expression filter for a database, call the Dbffile::setFilter method: dObject> setFilter(db,#(recno(db) > 5L) & (recno(db) < 15L)); The above example creates a filter for a Dbffile making it appear that only the records having record numbers between 6 and 14 inclusive actually exist in the file. The expression can be any valid dObject expression, and setting a filter in this way affects every future operation done on the database, including repositioning with the Dbffile::top, Dbffile::bot, Dbffile::skip, and Dbffile::go methods, as well as editing within the interactive DBASE editor. When created, Dbffile objects have an implied filter of logical(true), which succeeds for any record. To clear the filter for a Dbffile object, use the Dbffile::clearFilter() method: dObject> clearFilter(db); - 57 - dObject Version 1.0 (c) 1991 Intelligent Systems Research Collections can be created from DBASE fields using the "asCollection" method. The argument to this method is an expression to evaluate for each record in the DBASE file. The Collection returned contains one entry for the value of the expression for each record. The filtering process descibed above applies to filter out unwanted records. The following is an example of how to create a menu using information from a DBF file using a Collection as the list of items to show in the menu: /* create a menu of all the last names within a range of records in the dbf file */ d = new(Dbffile,"patient"); top(d); d = setFilter(d,#(recno(d) >= 8L) & (recno(d) <= 15L)); a = sort(asCollection(d,#trim(lname))); m = new(Menu,3,3,5,31,3,a," Last Name "); c = choice(m,1); remove(m); ? "your menu choice was ",c; 12.5 Using DBASE Index Files Records containing field values of interest can be accessed much more quickly using DBASE index files than can be using the "locate" method described above. dObject provides the built-in Ndxfile class to represent DBASE index files. To open an existing index file and associate it with a Dbffile variable, use the "useIndex" method of the Dbffile class. This method returns a new Ndxfile variable: dObject> db = new(Dbffile,"patient"); dObject> ndx = useIndex(db,"patient"); This method opens the named index (with the default extension of .NDX) and associates it with the Dbffile. This permits the Ndxfile::seek method to be used to position the current record in the Dbffile: dObject> seek(db,"1"); To create a new index file, use the "createIndex" method of the String class. The "self" argument in this case is the name of the index file to create, followed by a String containing the expression to evaluate for the index, and finally an Int indicator specifying if the index is to be unique (0=not unique, 1=unique). It also returns a new Ndxfile variable: dObject> ndx = createIndex("test","test",1); - 58 - Chapter 12: DBASE File Programming The following program demonstrates how to create an index file and use it to access fields within a Dbffile: /* create an index file for a database */ db = new(Dbffile,"patient"); index = createIndex(db,"patient","LNAME",0,0); ? "type of index is ",type(index); close(db); /* open the index and print out records in index order */ db = new(Dbffile,"patient"); useIndex(db,"patient"); top(db); while(!eof(db)) { ? recno(db)," ",lname; skip(db,1L); } close(db); 12.6 Using Relations dObject provides a facility to relate two DBF files throught the use of the Dbffile::setRelation() method. Calling this method creates a relation between a controlling database (the self parameter) and a related database. Each time the controlling database is re-positioned (using the Dbffile::go(), Dbffile::seek(), Dbffile::top(), or Dbffile::bot() methods), the related database is re-positioned by looking up an expression in an index file. If no index file is specified when the relationship is created, then the expression is evaluated and interpreted as a record number to go to in the related database. The following example illustrates the use of relations in dObject: /* demonstrate the dObject relation facility between two related DBF files, first, create a customer file with customer names */ custDb = createDbf("customer",[ ["cId",'N',8,0], ["cName",'C',32,0], ["cAddress",'C',48,0], ["cCity",'C',16,0], ["cState",'C',2,0], ["cZip",'C',5,0]]); - 59 - dObject Version 1.0 (c) 1991 Intelligent Systems Research /* fill in some test customer names */ #define MAXCUST 5 for(i=0;i<MAXCUST;i=i+1) { cId = i; cName = "name"+asString(i); cAddress = ""; cCity = "Chicago"; cState = "IL"; cZip = "60640"; ? "writing record ",i; write(custDb,0L); } close(custDb); /* create a database of customer purchases */ purchaseDb = createDbf("purchase",[ ["cId",'N',8,0], ["pItem",'C',32,0], ["pDate",'D',0,0], ["pAmount",'N',8,2]]); /* create some test data */ for(i=0;i<MAXCUST;i=i+1) for(j=0;j<2;j=j+1) { cId = i; pItem = "item"+asString(i); pDate = date(); pAmount = 5.25; write(purchaseDb,0L); } close(purchaseDb); /* find the purchases for customer #3 */ custDb = new(Dbffile,"customer"); purchaseDb = new(Dbffile,"purchase"); ndx = createIndex(purchaseDb,"CID","cId",0,0); setRelation(custDb,"cId",select(purchaseDb),select(ndx),0); top(custDb); locate(custDb,"cId",3); ? "record number for customer 3 is ",recno(custDb); ? "customer id field in purchase database is ",recno(purchaseDb); - 60 - Chapter 12: DBASE File Programming 12.7 Editing DBASE Files Using the built-in Window::say() and read() methods and the "Field" class, the file DBFLIB.DO provides an example of a DBASE full-screen editor that is invoked by sending the "edit" message to a Dbffile object. You can include this editor in your own programs as is, or customize it to fit your own application. When invoked, the editor will display the field name and value for each field within the database in the current window, at the current record position. The "edit" method is implemented in the following library of Dbffile methods: /* DBFLIB.DO This is a collection of methods for handling DBASE files Includes: Dbffile::displayStructure(self) Dbffile::copyStructure(self) Dbffile::list(self) Dbffile::edit(self) */ #include "keydef.do" #include "colors.do" /* Dbffile::displayStructure(self) this methods prints a description of the structure of a DBASE file similar to that in the DBASE DISPLAY STRUCTURE command */ method Dbffile::displayStructure(self) { ? "Structure for\t\t",name(self); ? "Last udpate:\t\t",date(self); ? "Number of records:\t",numRecords(self); fields = structure(self); ? "FIELD\t\t\tTYPE\tLEN\tDEC"; for(i=1;i<numFields(self);i=i+1) { f = at(fields,i); ? format(at(f,1),"%-24s"),at(f,2),"\t", at(f,3),"\t",at(f,4); } } /* Dbffile::copyStructure(self,newname) this method copys the structure of self to a new database with name of "newname" only the structure of self is copied; no records are copied */ - 61 - dObject Version 1.0 (c) 1991 Intelligent Systems Research method Dbffile::copyStructure(self,newname) { l = structure(self); create(newname,l); } /* Dbffile::list(self) this method lists the records in a Dbffile to the screen */ method Dbffile::list(self) { top(self); fields = structure(self); newline = set("newline"); set("newline",""); while(!eof(self)) { for(i=1;i<numFields(self);i=i+1) { f = at(fields,i); name = at(f,1); ? eval(asId(name))," "; } ? "\n"; skip(self,1L); } set("newline",newline); } /* The following methods implement a DBASE field editor using the dObject Window SAY and READ methods and the FIELD class. first, define a new class called MYFIELD that inherits the behavior of Field, but adds a prompt that is displayed at the bottom of the form */ inherit(Field,Myfield,["prompt"]); /* define a method to get the prompt field from a Myfield variable */ method Myfield::prompt(self) { return(slot(self,"prompt")); } /* this method will execute whenever the DOWN key is pressed from within a form */ method Window::myNextField(self) { n = num(currentField(self)); if(n < len(fields)) { - 62 - Chapter 12: DBASE File Programming f = at(fields,n+1); say(promptWindow,0,0,prompt(f),80,112); gotoField(self,nextField(self)); } } /* this method will execute whenever the UP key is pressed from within a form */ method Window::myPrevField(self) { n = num(currentField(self)); if(n > 1) { f = at(fields,n-1); say(promptWindow,0,0,prompt(f),80,112); gotoField(self,prevField(self)); } } /* this method implements a callable text editor for the contents of a field */ method Window::myEdit(self) { f = currentField(self); s = eval(asId(name(f))); if(class(s) == "String") { w = new(Window,1,31,3,name(f),5,5,10,40); display(s); remove(w); gotoField(self,f); } } /* edit a Dbffile using a full screen editor */ method Dbffile::edit(self) { /* make a window to run the editor in */ w = new(Window,1,FWHITE+LIGHTBLUE,FWHITE+LIGHTBLUE, name(self),0,0,24,80); /* create the DBASE form based on field definitions within self */ clearGets(w); - 63 - dObject Version 1.0 (c) 1991 Intelligent Systems Research sayExp(w,0,1,#name(self),len(name(self)),FWHITE+LIGHTBLUE); sayExp(w,0,20,#"Record=",7,FWHITE+LIGHTBLUE); sayExp(w,0,30,#recno(self),7,FWHITE+LIGHTBLUE); l = structure(self); fields = []; /* for each field in the DBF file, create: a SAY field with the name of the DBF field a GET field right next to it to read its value */ for(i=1;i<=numFields(self);i=i+1) { field_def = at(l,i); fname = at(field_def,1); % name is first element in field def len = at(field_def,3); if(len > 40) len = 40; say(w,i,1,fname,10,31); fields = append(fields,new(Myfield,w,i,15,fname,len,112, "Enter the "+asUpper(trim(fname))+ " field")); } /* execute the form */ top(self); promptWindow = new(Window,80,112,0,"",24,0,1,80); onKey(w,DOWN,#myNextField(w)); onKey(w,UP,#myPrevField(w)); onKey(w,F8,#myEdit(w)); say(promptWindow,0,0,prompt(at(fields,1)),80,112); read(w); remove(w); remove(promptWindow); } As another example, the following program displays a directory of DBF files in the current directory and edits the one selected from the menu: /* this program creates a window, and displays a menu of DBF files available in the current directory. When the user selects one, the DBF file editor is called to edit the fields and records */ - 64 - Chapter 12: DBASE File Programming w = new(Window,1,7,7," select DBF ",1,1,10,40); s = dir("","*.dbf"); while(s != "") { d = new(Dbffile,s); height = numFields(d)+2; edit(d); s = dir("","*.dbf"); } remove(w); 12.8 Closing DBASE Files To close a Dbffile, use the "close" method: dObject> close(db); To close all the open Dbffiles at once, use the Nil::closeAllDbfs method (this will close all open .NDX files also): dObject> closeAllDbfs(); 13.0 Graphics Programming 13.1 BGI Graphics dObject comes complete with a built-in graphics system based on the Borland Graphics Interface (BGI). The BGI provides over 70 methods for handling graphics, including methods to draw lines, arcs, circles, polygons, and other shapes; methods for filling shapes in a variety of styles; and methods for setting text in a variety of fonts. 13.2 Graphics Drivers To begin with, you must call the Int::initGraph() method to initialize the graphics system. This will put the screen into graphics mode and allow further calls to the BGI system. dObject comes with graphics drivers for the following graphics adapters: * CGA * MCGA * EGA * VGA - 65 - dObject Version 1.0 (c) 1991 Intelligent Systems Research * Hercules * AT&T 400-line * 3270 Graphics Adapter * IBM-8514 Graphics Adapter The self argument to Int::initGraph() is an integer flag specifying the device driver to use ( a value of 0 will detect the best driver to use): * 0 - autodetect * 1 - CGA * 2 - MCGA * 3 - EGA * 4 - EGA64 * 5 - EGAMONO * 6 - IBM8514 * 7 - Hercules * 8 - AT&T 400 * 9 - VGA * 10 - PC 3270 You can obtain the name of the current graphics driver through a call to the Nil::getDriverName() method. dObject provides the following methods for initializing and shutting down the BGI graphics system: NAME ARGUMENTS DESCRIPTION Int::initGraph self, Int, String initializes the BGI system; must be called before any other BGI method. Sets the graphics driver to self, the graphics mode to the Int arg, and the driver path to the String arg. - 66 - Chapter 13: Graphics Programming Nil::detectGraph returns a Collection of 2 Int values specifying the current graphics driver and mode. Nil::getDriverName returns a String containing the name of the current graphics driver. Int::getModeName self returns a String containing the graphics mode name for the mode with Int code of self. Int::getModeRange self returns a Collection of 2 Int values specifying the min and max mode values for the graphics driver with Int code of self. Int::setGraphMode self changes the graphics mode to self. Nil::getGraphMode returns an Int containing the current graphics mode. Nil::getMaxMode returns an Int containing the maximum mode number for the currently loaded driver. Nil::graphDefaults sets the graphics system to default values (see next section). Nil::closeGraph closes the graphics system, unloads the driver from memory, and restores the CRT to its original state before initGraph() was called. Nil::restoreCrtMode restores the CRT to its original state. 13.3 Default Graphics Settings You can set the graphics system to its default settings through a call to the Nil::graphDefaults() method. These defaults settings are as follows: * Viewport: mamimum device resolution * Clipping: on * Palette: default for drive * Background color: 0 * Drawing color: max color * Fill style: solid fill - 67 - dObject Version 1.0 (c) 1991 Intelligent Systems Research * Fill color: max color * Line style: solid line * Hardware font direction: horizontal * Font size: 1 * Font justification: left top * Current position: home (0,0) 13.4 Current Graphics Position The BGI system maintains the current X,Y graphics co-ordinate that is referred to as the current position (CP). The current position can be obtained through calls to the Nil::getx() and Nil::gety() methods, each of which return an Int value. The CP can be set using the Int::moveto() and Int::moveRel() methods, with the self arg equal to the X value to move to, and the first argument being an Int Y co-ordinate. Int::moveTo() uses and absolute co-ordinate, whereas Int::moveRel() moves relative to the current position: /* move the graphics CP */ moveto(100,100); % now at 100,100 moveRel(100,100); % now at 200,200 dObject provides the following methods for maintinaing the graphics CP: NAME ARGUMENTS DESCRIPTION Nil::getX returns the x co-ordinate of the CP Nil::getY returns the y co-ordinate of the CP Int::moveTo self, Int moves the CP to X,Y of self, Int arg Int::moveRel self, Int moves the CP the X,Y relative distance of self, Int arg Nil::getMaxX returns the max X value for the current graphics driver and mode Nil::getMaxY returns the max Y value for - 68 - Chapter 13: Graphics Programming the current graphics driver and mode 13.5 Drawing Lines Lines are drawn using the Int::line() method, passing it the X,Y positions of the beginning and end points. The following example draws a line from the point 5,5 to the point 100,100: dObject> line(5,5,100,100); The following methods are provided for drawing lines: NAME ARGUMENTS DESCRIPTION Int::setLineStyle self, Int, Int sets the current line style to the code in self; sets the current pattern to the first Int arg code, and the current thickness to the second Int arg. Line style codes are 0=solid, 1=dotted, 2=center, 3=dashes, 4=user-defined. You can define a line style by using a 16-bit pattern in the first Int arg, where whenver a bit in the pattern is set to one, the corresponding pixel in the line is drawn in the current drawing color. For example, a solid line is represented by the value $FFFF (all one's), and a dashed line is $3333 or $0F0F. Thickness codes in the second Int arg are 0=1 pixel wide, 3=3 pixels wide. Nil::getLineSettings returns collection of 3 Int args representing current line style, user-defined pattern, and thickness code as described above. Int::line self, Int, Int, Int draws a line in the current drawing color. Arguments are X,Y of start point and X,Y of end point. Int::linerel self, Int draws a line in the current drawing color from current position to relative offset - 69 - dObject Version 1.0 (c) 1991 Intelligent Systems Research of self, Int arg. Int::lineto self, Int draws a line in the current drawing color from current position to X,Y position of self, Int arg. Int::setWriteMode self sets the writing mode for line drawing to self; if self = 0 the line will overwrite what is on the screen; if self=1 the line pixels will be XOR'd with the pixels on the screen. 13.6 Drawing Circles The following methods are provided for drawing circles and arcs: NAME ARGUMENTS DESCRIPTION Int::arc self, Int, Int, Int, draws a circular arc in the Int current drawing color. Arguments are X,Y center, start angle, end angle, and radius. Int::circle self, Int, Int draws a circle in the current drawing color. Arguments are X,Y of center, and radius. Nil::getArcCoords returns a Collection of 6 Int values containing the x,y center point, x,y start pos, and x,y end pos of the arc. This is useful if you need to make a line meet at the end of an arc. 13.7 Drawing Ellipses and Pie Charts The following methods are provided for drawing ellipses and pie charts: NAME ARGUMENTS DESCRIPTION Int::ellipse self, Int, Int, Int, draws an ellipse in the Int, Int current drawing color. Args are center point X,Y, start angle, end angle, and X and Y radius. Int::fillEllipse self, Int, Int, Int draws an ellipse and fills it with the current fill - 70 - Chapter 13: Graphics Programming pattern in the current fill color. Args are X, Y, X radius, and Y radius. Int::pieSlice self, Int, Int, Int, draws and fills a pie slice Int using current fill pattern and drawing color. Arguments are X,Y center, start angle, end angle, and radius. Int::pieSliceXY self, Int, Int, Int, draws and fills an Int, Int elliptical pie slice using current fill pattern and drawing color. Arguments are X,Y center, start angle, end angle, X radius, and Y radius. Nil::getAspectRatio returns Collection of 2 Int value representing the x and y aspect ratio correction values of the current graphics mode. setAspectRatio self, Int sets the x and y aspect-ratio correction factors to self and Int arg respectively. 13.8 Drawing Rectangles and Bars dObject provides the following methods for drawing rectangles, bar graphs, and polygons: NAME ARGUMENTS DESCRIPTION Int::rectangle self, Int, Int, Int draws a rectangle in the current line style, thickness, and drawing color. Arguments are left, top, right, and bottom co-ordinates of the rectangle to draw (from (left,top) to (right,bottom)). Int::bar self, Int, Int, Int draws a rectangular bar in the current line style, thickness, and drawing color, and fills it using the current fill pattern and fill color. Arguments are left, top, right, and bottom co-ordinates of the rectangle to draw (from - 71 - dObject Version 1.0 (c) 1991 Intelligent Systems Research (left,top) to (right,bottom)). Int::bar3d self, Int, Int, Int, draws a rectangular 3-D bar Int, Int in the current line style, thickness, and drawing color, and fills it using the current fill pattern and fill color. Arguments are left, top, right, and bottom co-ordinates of the rectangle to draw (from (left,top) to (right,bottom)), the depth of the bar, and a flag indicating if a top to the bar should be drawn (0=no, 1=yes). 13.9 Drawing Polygons dObject provides the following methods for drawing polygons: NAME ARGUMENTS DESCRIPTION Collection::drawPoly self draws a polygon with as many points as Int value pairs in the collection; each Int pair is an x,y co-ordinate of a vertex on the polygon. Collection::fillPoly self draws a polygon with as many points as Int value pairs in the collection and fills it using the current fill style and fill color; each Int pair is an x,y co-ordinate of a vertex on the polygon. 13.10 Palettes The BGI graphics screen consists of an array of pixels controlled by a color table called a palette. The background color always corresponds to pixel value 0. The drawing color is the value to which pixels are set when lines or shapes are being drawn. You can select a drawing color with the Int::setColor() method. NAME ARGUMENTS DESCRIPTION Int::setBkColor self sets the current background color to self Nil::getBkcolor self returns the current - 72 - Chapter 13: Graphics Programming background color Int::setColor self sets the current drawing color to self Nil::getColor returns the current drawing color Nil::getMaxColor returns the maximum color value available in the current graphics mode Int::setPalette self, Int changes the color value stored under self to the color in the Int arg Collection::setAllPaletteself sets list of new palette colors. self must be a Collection of 8 Int values specifying the colors. 13.11 Filling Shapes You can fill the shapes drawn with the circle, ellipse, bar, and polygon shape drawing methods with the Int::floodFill() method, or combine drawing and filling into one step with the fillPoly() and pieSlice() methods. You can select a predefined fill pattern with setFillStyle, and define your own fill pattern with setFillPattern(). The predefined fill pattern codes recognized by Int::setFillStyle() are as follows (as defined in the included file BGIDEF.DO): * 0 (EMPTY_FILL) - fill with background color * 1 (SOLID_FILL) - solid fill * 2 (LINE_FILL) - fill with ---- * 3 (LTSLASH_FILL) - fill with /// * 4 (SLASH_FILL) - fill with ///, thick lines * 5 (BKSLASH_FILL) - fill with backslash, thick lines * 6 (LTBACKSLASH_FILL) - fill with backslash * 7 (HATCH_FILL) - light hatch fill * 8 (XHATCH_FILL) - heavy cross hatch fill * 9 (INTERLEAVE_FILL) - interleaving line fill * 10 (WIDE_DOT_FILL) - widely spaced dot fill * 11 (CLOSE_DOT_FILL) - closely spaced dot fill - 73 - dObject Version 1.0 (c) 1991 Intelligent Systems Research * 12 (USER_FILL) - user-defined fill pattern (see Collection::setFillPattern()) The following methods are provided for filling shapes: NAME ARGUMENTS DESCRIPTION Nil::getFillSettings returns a Collection of 2 Int values; the first is the current fill pattern; the second is the current fill color Int::setFillStyle self, Int sets the current fill pattern to the predefined pattern with a code of self and the current fill color to the Int arg Collection::setFillPatternself, Int sets the current fill pattern to a user-defined Collection of 8 Int color values. Each Int value represents a byte of 8 pixels; whenever a bit in the pixel pattern is set to 1, the corresponding pixel will be plotted. The Int arg is the fill color to use. Nil::getFillPattern returns the current user-defined fill pattern as a Collection of 8 Int values. Int::floodFill self, Int, Int fills an enclosed area on the graphics screen. Self and the first Int arg form a "seek point": within the enclosed area to be filled. The are bounded by the color indicated in the second Int arg is flooded with the current fill pattern and fill color. If the seed point is within an enclosed area, the the inside will be filled. If the seed is outside the enclosed the area, then the exterior will be filled. - 74 - Chapter 13: Graphics Programming 13.12 Fonts and Text in Graphics Mode You can also output text in a variety of fonts, sizes, and styles from within dObject's BGI graphics mode. Text output is accomplished by calling the String::outText() or Int:outTextXY() methods after defining a current character font. Text justification constants in horizontal mode: * 0 - left horizontal * 1 - center horizontal * 2 - right horizontal Text justification constants in vertical mode: * 0 - bottom vertical * 2 - top vertical dObject provides the following methods for manipulating text in graphics mode: NAME ARGUMENTS DESCRIPTION String::outText self outputs a string to the current graphics position (CP). Int::outTextXY self, Int, String outputs String arg to x,y location of self, Int arg String::textHeight self returns height of self in pixels as Int String::textWidth self returns width of self in pixels as Int Nil::getTextSettings returns Collection of 4 Int values indicating current text font, direction, size, and justification Int::setTextJustify self, Int sets justification to horizontal code of self and vertical code of Int arg. Horizontal values: 0=left,1=center,2=right Vertical values: 0=bottom,1=top Int::setTextStyle self, Int, Int sets current text font to self; sets current direction to first Int arg, and current char size to second - 75 - dObject Version 1.0 (c) 1991 Intelligent Systems Research Int arg. Text direction codes are 0=horizontal (left to right), 1=vertical (bottom to top). Int::setUserCharSize self, Int, Int, Int sets width and height ratio for stroked fonts. Sets scale factors for x width, x height, y width, and y height to self and the 3 Int args respectively. 13.13 Viewports Your system contains between one and four screen-page buffers where screen images are stored dot-by-dot, depending on the graphics hardware installed. You can specify which screen page is active (where graphics methods place their output) and which page is visible using the Int::setActivePage() and Int::setVisualPage() methods. You can specify a region of the display screen where clipping is active through a call to the setViewPort() method. dObject provides the following viewport-related methods: NAME ARGUMENTS DESCRIPTION Int::setViewPort self, Int, Int, Int, sets the current viewport to Int the absolute screen co-ordinates left, top, right, bottom corresponding to the self argument and the first three Int arguments respectively. The final Int arg is a flag indicating if clipping is on or off (0 = off, 1 = on). Nil::getViewSettings returns a Collection of 5 Int value specifying the left, top right, and bottom screen co-ordinates of the current viewport, and an Int flag indicating if clipping is on or off. Int::setActivePage self sets the active graphics page to page number of self. Int::setVisualPage self sets the visible graphics page to page number of self. Nil::clearViewPort self clears the current viewport and moves the CP to (0,0). Nil::clearDevice self clears the entire screen and - 76 - Chapter 13: Graphics Programming moves the CP to (0,0). 13.14 Pixels and Images The BGI system also provides several methods for manipulating images and pixels on the graphics screen: NAME ARGUMENTS DESCRIPTION Int::getPixel self, Int returns the pixel color at location x,y specified by self and Int arg Int::putPixel self, Int, Int sets the pixel at location x,y (self, Int arg) to color specified by second Int arg Int::getImage self, Int returns image stored at x,y of self, Int arg Int::imageSize self, Int, Int, Int returns an Int number of bytes necessary to store a rectangular area of the screen. Args are left, top, right, and bottom co-ordinates of the region. Int::putImage self, Int, Image, Intwrites an image to the screen at x,y of self, first Int arg. Second Int arg specifies how bits of the image will be combined with bits already on the screen: copy = 0, xor = 1, or = 2, and = 3, not = 4. - 77 -